Skip to main content

Hat Lab Setup Guide

The Hat Lab is a three-step customization flow that lets shoppers pick a hat style, choose a color variant, and finish their personalization on the product page without any apps. This guide walks through the merchant-facing configuration from start to finish.

1. Prerequisites​

  • Styles collection: Create a collection that contains every product you want to feature in Step 1 of the wizard. The Hat Lab section pulls directly from the collection you choose in its settings.
  • Variant color option: Ensure each product has a variant option for color (or similar) and upload featured images per color. Step 2 reads the option name you supply (defaults to "Color") and uses the variant's featured image for the swatch preview.
  • Product customizer blocks: Add your desired line item property blocks (e.g., swatches, text inputs) to the product template so Step 3 can collect custom details. See Custom line item properties for block guidance.
  • Product metafields (optional): To display features and price indicators on Step 1 cards, create the following metafields in Settings → Custom data → Products:
    • Features (custom.features): A "List of single-line text" metafield. Add up to 4 short feature descriptions per product (e.g., "Adjustable strap", "Breathable mesh", "One size fits most").
    • Price Indicator (custom.price_indicator): A "Number (integer)" metafield with a value of 1, 2, or 3. This displays as dollar signs ($, $$, $$$) to indicate relative price range.

2. Theme settings​

  1. Open Theme settings → Hat Lab and set the following values:
    • Hat Lab product tag: Any product with this tag will automatically show the Step 3 progress bar when viewed directly. Keep it consistent with the tag you plan to use (default hat-lab).
    • Hat Lab page slug: The handle of the page that will host the wizard (default hat-lab).
  2. (Optional) Add the same tag to your "hidden tags" list in Theme settings if you want to keep these products out of standard collections while still allowing direct access via the Hat Lab page.

3. Create the Hat Lab page​

  1. In Shopify admin, go to Online Store → Pages and create a new page. Give it a handle that matches the slug from Theme settings (e.g., hat-lab).
  2. Assign the page.hat-lab template to this page. The template ships with the Hat Lab section preloaded and is ready for customization.
  3. Open the page in the Theme Editor to configure the section.

4. Configure Step 1 (choose a style)​

Inside the Theme Editor, select the Hat Lab section and configure the Styles collection picker. The section renders a responsive grid of cards for each product in that collection, including featured images, short descriptions, optional feature lists, and starting price.

Key settings:

  • Show product descriptions toggles the product description on each card.
  • Show product features list displays up to 4 bullet points from the Features metafield (custom.features) on each card. Make sure you've created and populated this metafield on your products (see Prerequisites).
  • Step 1 title/description let you rewrite the hero text shown above the grid for campaign-specific messaging.
  • Card layout controls (max width, image ratio, products per row) are available in the section settings to fine-tune spacing on different screen sizes.

Sorting and filtering​

If your collection has many products, enable Sorting and filtering to help shoppers narrow down options:

  • Enable sorting and filtering: Master toggle to show the filter bar above the product grid.
  • Available filter tags: Enter comma-separated tags that match your product tags (e.g., Men, Women, Kids). Each tag becomes a clickable filter button.
  • Default filter tags: Pre-select specific filters when customers land on the page (e.g., Men to show men's hats by default).
  • Enable sorting dropdown: Show a sort dropdown for price and alphabetical ordering.
  • Default sort order: Set the initial sort (manual, price low-high, price high-low, A-Z, Z-A).
  • Filter button behavior: Choose between hiding non-matching products (filter mode) or showing matching products first (sort mode).

Customers can select multiple filters simultaneously. Click "Clear all" to reset filters and sorting.

Price indicator​

Enable Show price indicator to display a dollar sign price range ($, $$, $$$) on each product card. This feature requires the Price Indicator metafield (custom.price_indicator) to be set on each product with a value of 1, 2, or 3 (see Prerequisites).

Additional options become available when enabled:

  • Price indicator alignment: Position the price on the left, center, or right of the card.
  • Price indicator size: Choose small, medium, or large text sizing.
  • Match price indicator color to title: When enabled, the price uses the same color as the product title for visual consistency.
  • Price indicator color: Set a custom color when not matching the title (e.g., a green or accent color to draw attention to pricing).

Card color customization​

Under Step 1: Card Colors, override the default product card styling:

  • Card background color: Sets the card container background.
  • Card text color: Sets the title, description, and price text color.
  • Card border color: Sets the card border color.

Leave these empty to use the default white background with dark text.

When a shopper clicks a style card, they move to Step 2 with the product handle passed as a URL parameter. The wizard also stores your heading/subheading styling choices so they appear consistently on the product page later.

5. Configure Step 2 (choose a color)​

Step 2 is generated dynamically to fetch the selected product's variants. Important settings:

  • Variant color option name: Tell the section which variant option represents color (default Color). If your products use "Patch" or another term, update the setting so the correct option values are displayed.
  • Step 2 copy: Customize the title, description, and "Selected style" label in the section settings to align with your brand tone.
  • Button styling: Adjust the Step 2 button colors, hover states, and border radius within the section to match your theme palette.

Swatch color customization​

Under Step 2: Swatch Colors, override the default variant swatch styling:

  • Swatch card background color: Sets the swatch container background (visible for card-style swatches or when images have transparency).
  • Swatch label text color: Sets the variant label text color below each swatch.
  • Swatch border color: Sets the border around swatch images.

Leave these empty to use the default white background with dark text.

Available variants show as clickable swatches that link to the product page with ?hatlab=1&variant={variant_id}. Sold-out colors remain visible but disabled so shoppers understand availability.

6. Step 3 on the product page​

When the customer lands on /products/{handle}?hatlab=1&variant={id}, the product template detects the Hat Lab context and:

  • Displays the same three-step progress UI and selected variant callout above your regular product form.
  • Hides the native variant selectors so the page focuses on your custom line item property blocks and any Hat Lab messaging.
  • Preselects the variant ID from the URL and keeps the "Selected Color" text updated as variants change.
  • Applies your stored heading/subheading styles, progress colors, and button text to ensure visual continuity with Steps 1–2.

Because the Hat Lab relies on standard product templates at this step, you can continue using blocks like Product swatch group, Product custom select, and any additional content around the form. Just make sure those blocks use the same property keys referenced in earlier steps if you need the values carried through the flow.

7. Optional styling controls​

The Hat Lab section exposes extensive design controls for progress bars, selected boxes, pagination, and button colors for both Step 2 and the Step 3 product experience. Tweak these to match your brand without editing code.

You can also adjust the section width, padding, color scheme, and SEO handling (noindex toggle) directly in the section settings.

8. Launch checklist​

  • Products are tagged with your Hat Lab product tag and assigned to the Styles collection.
  • Variant featured images exist for every color you offer so swatches look polished.
  • (Optional) If using the features list, create the Features metafield (custom.features) and populate it on each product.
  • (Optional) If using the price indicator, create the Price Indicator metafield (custom.price_indicator) and set values (1-3) on each product.
  • Custom line item property blocks are present on the product page template and use consistent keys.
  • Optional fee products are configured if certain selections should add surcharges. See Custom Option Fees.
  • (Optional) If using sorting and filtering, ensure products have the appropriate tags that match your filter tag list.
  • (Optional) If using card or swatch color customization, verify colors maintain sufficient contrast for accessibility.
  • (Optional) If enabling the price indicator, choose alignment and sizing that fits your card layout.
  • Test the full flow on desktop and mobile: /pages/hat-lab?step=1 → Step 2 → product page with hatlab=1 to confirm the progress bar, variant selection, and custom properties all work together.

With these steps complete, the Hat Lab experience will guide customers through a streamlined customization journey that feeds directly into Shopify's native cart and order management.

The idea of the Hat Lab is credited to Kevin over at Meraki Headwear. He was amazing to let us build it not only for him, but to add it as a feature in our theme!